Providers

Overview (C4 Component)

Black-box description of components

Component	Responsibility	Provided Interface(s)	Consumed Interface(s)
ProviderController	Entry point for provider CRUD & query.	REST /api/v1/providers/** (OpenAPI)	—
ProviderService	Executes use-cases (create, update, search); enforces authorisation and builds pageable queries.	Spring service API	ProviderRepository, ProviderSpecificationFactory, ProviderMapper, CurrentUserService
ProviderRepository	Persistence of Provider aggregate; supports dynamic Specifications & paging.	Spring-Data JPA	MySQL via JDBC
*ProviderSpecificationBuilder	Composes JPA Specification<Provider> from provider+truck filter DTOs.	Java class	TruckSpecificationBuilder (fleet module)
ProviderMapper / AddressMapper / ContactMapper	MapStruct converters between entities/embeddables and DTOs.	Java interface	—
Entities & Embeddables (Provider, Address, Contact)	ORM layer mapping; Provider contains @Formula fields for rating and confirmed-quote count.	JPA	—

Important internal interfaces

Name	Signature / Protocol	Notes
createProvider	POST /api/v1/providers – body ProviderRequest	ES admin only; returns 201 Created + Location header with ops-code URI.
getProviders	GET /api/v1/providers – query params: name, opsCode, countryOfOperations, techSpecs (Base64 JSON), paging & sorting	Builds combined Provider+Truck filter; responds with list of ProviderListItem.
getProviderByOpsCode	GET /api/v1/providers/{opsCode}	Public for authenticated users.
updateProvider	PUT /api/v1/providers/{opsCode}	Allowed for ES admin or the provider itself; rejects ops-code mismatch.